﻿/* Original Author:  Dominick O'Dierno
 * Date: 4/4/2008   odiernod@gmail.com     --Originally intended for use with DOMercury:  http://www.odierno.com/domercury
 * Description: Defines an interface to allow DOMercury to provide core functionality to plugins
 * 
 * --CHANGELOG--
 * 
 * */

using System;
using System.Collections.Generic;
using System.Text;
using System.Collections.Specialized;
using System.Windows.Forms;
using System.Xml;
using DOMercury.Utilities;

namespace DOMercury.Interfaces
{
    /// <summary>
    /// Provides access to the core DOMercury Engine.  Your DOMercuryUserInterface will recieve an instance of this interface to use to make DOMercury API calls.
    /// </summary>
    public interface IDOMercury
    {
        //IndexManager
        /// <summary>
        /// Returns the current index to the main DOMercury Index
        /// </summary>
        void ReturnMainIndex();

        /// <summary>
        /// Sets the proper Autocomplete source configuration for a search textbox
        /// </summary>
        /// <param name="type">the ItemType of the currently selected item</param>
        /// <returns></returns>
        System.Windows.Forms.AutoCompleteSource ItemAutoCompleteSource(string type);

        /// <summary>
        /// Sets the proper Autocomplete source configuration for a search textbox
        /// </summary>
        /// <param name="Parameters">A list of possible IItem parameters</param>
        /// <param name="AutoCompleteMode">The suggested autocomplete mode for a parameters textbox</param>
        /// <param name="AutoCompleteSource">The suggested autocompletesource for a parameters textbox</param>
        /// <param name="CustomSource">A possible custom autocomplete source for a parameters textbox</param>
        /// <param name="pType">The Parameter Type of the currently selected action</param>
        /// <param name="iType">The Item Type of the currently selected Item</param>
        void ChangeParametersAutoCompleteSource(out List<IItem> Parameters, out System.Windows.Forms.AutoCompleteMode AutoCompleteMode, out System.Windows.Forms.AutoCompleteSource AutoCompleteSource, out AutoCompleteStringCollection CustomSource, string pType, string iType);

        /// <summary>
        /// The Parent Item of the current sub index
        /// </summary>
        IItem ParentItem
        {
            get;
        }

        /// <summary>
        /// Dive into a sub index based on the currently selected Item, Action, and Parameters
        /// </summary>
        /// <param name="item">Item to dive into a sub index from</param>
        /// <param name="itemtext">the currently typed search text</param>
        /// <param name="action">The currently selected action</param>
        /// <param name="param">the currently selected parameters. If text, should be a TextItem</param>
        /// <returns></returns>
        bool SetSubIndex(IItem item, string itemtext, IAction action, IItem param);

        /// <summary>
        /// Pop the current index to the previous index
        /// </summary>
        void PreviousIndex();

        /// <summary>
        /// The search text of the parent index
        /// </summary>
        string ParentText
        {
            get;
        }

        /// <summary>
        /// Create a Text Item from the supplied string
        /// </summary>
        /// <param name="itemtext">string to have a TextItem wrapped around</param>
        /// <returns></returns>
        List<IItem> ProvideTextItem(string itemtext);

        /// <summary>
        /// Get results from the current index based on search text
        /// </summary>
        /// <param name="text">The search text with which to retrieve results</param>
        /// <returns>The results</returns>
        List<IItem> GetItems(string text);

        /// <summary>
        /// Get results from the Main DOMercury Index based on search text
        /// </summary>
        /// <param name="text">The search text with which to retrieve results</param>
        /// <returns>The results</returns>
        List<IItem> GetItemsFromMainIndex(string text);

        /// <summary>
        /// Get a certain number of results from the Main DOMercury Index based on search text
        /// </summary>
        /// <param name="text">The search text with which to retrieve results</param>
        /// <param name="NumResults">The maximum number of results returned. NOTE: This function may return less results depending on the possible number of matches</param>
        /// <returns>The results</returns>
        List<IItem> GetItemsFromMainIndex(string text, int NumResults);

        //PluginManager
        /// <summary>
        /// Returns true if the ItemType supports a sub index
        /// </summary>
        /// <param name="type">the ItemType of an IItem</param>
        /// <returns></returns>
        bool HasSubIndex(string type);

        //IconManager
        /// <summary>
        /// returns a bitmap based on the DisplayDescription of an IItem, or ActionType of an IAction
        /// </summary>
        /// <param name="filename">The DisplayDescription of an IItem or ActionType of an IAction</param>
        /// <returns></returns>
        System.Drawing.Bitmap GetIconImage(string filename);

        //PathFinder
        /// <summary>
        /// Returns a valid path if found from the path or keyword passed in.  Ex:  mydocs will return the path to the My Documents folder
        /// </summary>
        /// <param name="path"></param>
        /// <returns></returns>
        string FindPath(string path);

        /// <summary>
        /// Returns true if the path passed in is a valid file or network path
        /// </summary>
        /// <param name="path"></param>
        /// <returns></returns>
        bool IsPath(string path);

        //TypeManager
        /// <summary>
        /// Gets all the possible actions referring to an ItemType of an IItem
        /// </summary>
        /// <param name="Type">The ItemType of the IItem to get Actions for</param>
        /// <param name="actions"> a reference to a list of IActions to populate</param>
        /// <returns>true if actions are found for the ItemType</returns>
        bool GetActions(string Type, ref List<IAction> actions);

        //ActionManager
        /// <summary>
        /// Performs the Action on the IItem with the selected parameters
        /// </summary>
        /// <param name="Item">The Item to have the action performed on</param>
        /// <param name="Action">The Action to perform</param>
        /// <param name="specialParams">Any required or optional parameters for the Action</param>
        /// <returns></returns>
        bool Perform(IItem Item, IAction Action, object specialParams);

        //SelectedItemsGrabber
        /// <summary>
        /// Returns an ItemsList of selected Items from a Windows Explorer Window if a Windows Explorer Window was the active window right before DOMercury was invoked.
        /// </summary>
        /// <returns></returns>
        Items.ItemsList GetSelectedItems();

        /// <summary>
        /// Disposes and generates a new instance of the current IDOMercuryUserInterface.  This does not Invoke DOMercury
        /// </summary>
        void RestartInterface();

        /// <summary>
        /// Forces a reinvoke of the DOMercury Interface.  Useful for starting DOMercury with a sub index after an action
        /// </summary>
        void ReinvokeInterface();

        /// <summary>
        /// Shows the DOMercury Options Form
        /// </summary>
        void ShowOptions();

        /// <summary>
        /// Be careful with this one, it will close the application.  This should only be used by UserInterface plugins
        /// </summary>
        void ExitDOMercury();

        /// <summary>
        /// Returns true if the current index is the main index
        /// </summary>
        bool CurrentIndexIsMainIndex
        {
            get;
        }

        /// <summary>
        /// Returns the saved XmlDocument holding the plugin's settings
        /// </summary>
        /// <param name="pluginName">The name of the plugin, or other key you are using to store settings</param>
        /// <returns>An xmldocument based on the key passed in</returns>
        XmlDocument GetPluginSettingsXml(string pluginName);

        /// <summary>
        /// Returns the saved XmlDocument holding the interface's settings
        /// </summary>
        /// <param name="interfaceName">The name of the interface, or other key you are using to store settings</param>
        /// <returns>An xmldocument based on the key passed in</returns>
        XmlDocument GetInterfaceSettingsXml(string interfaceName);

        /// <summary>
        /// Saves the settings (XmlDocument) into DOMercury's Configuration Manager
        /// </summary>
        /// <param name="pluginName">the key to use for the settings</param>
        /// <param name="pluginSettings">The settings to save</param>
        void SavePluginSettings(string pluginName, object pluginSettings);

        /// <summary>
        /// Saves the settings (XmlDocument) into DOMercury's Configuration Manager
        /// </summary>
        /// <param name="interfaceName">the key to use for the settings</param>
        /// <param name="interfaceSettings">The settings to save</param>
        void SaveInterfaceSettings(string interfaceName, object interfaceSettings);

        /// <summary>
        /// Retrieves a dictionary of Interface Settings
        /// </summary>
        /// <param name="InterfaceName">Key for settings</param>
        /// <returns>dictionary of settings matching key</returns>
        SerializableDictionary<string, object> GetInterfaceSettingsDict(string InterfaceName);
        /// <summary>
        /// Retrieves a dictionary of plugin Settings
        /// </summary>
        /// <param name="pluginName">Key for settings</param>
        /// <returns>dictionary of settings matching key</returns>
        SerializableDictionary<string, object> GetPluginSettingsDict(string pluginName);
        /// <summary>
        /// Saves a dictionary of settings
        /// </summary>
        /// <param name="InterfaceName">The key to use for the settings</param>
        /// <param name="settings">The settings to save</param>
        void SaveInterfaceSettings(string InterfaceName, SerializableDictionary<string, object> settings);
        /// <summary>
        /// Saves a dictionary of settings
        /// </summary>
        /// <param name="pluginName">The key to use for the settings</param>
        /// <param name="settings">The settings to save</param>
        void SavePluginSettings(string pluginName, SerializableDictionary<string, object> settings);
    }
}
